Configuration of jobs with .gitlab-ci.yml

Jobs

.gitlab-ci.yml allows to specify an unlimited number of jobs. Each job must have a unique name that can not be the keywords in GitLab CI/CD. A job is defined by a list of parameters, the parameters define the job behavior. For example:

job_name:
  script:
    - rake spec
    - coverage
  stage: test
  only:
    - master
  except:
    - develop
  tags:
    - ruby
    - postgres
  allow_failure: true
Keyword Required Description
script yes Defines a shell script, which is executed by Runner
image no Use docker image, covered in Using Docker images
services no Use docker services, covered in Using Docker images
stage no Defines a job stage (default: test)
type no Alias for stage
variables no Define job variables on a job level
only no Defines a list of git refs for which job is created
except no Defines a list of git refs for which job is not created.
tags no Defines a list of tags which are used to select Runner
allow_failure no Allow job to fail. Failed job doesn't contribute to commit status
when no Define when to run job. Can be "on_success", "on_failure", "always" or "manual"
dependencies no Define other jobs that a job depends on, can pass artifacts between them
artifacts no Define list of job artifacts
cache no Define list of files will be cached between subsequent runs
before_script no Override a set of commands that are executed before job
after_script no Override a set of commands that are executed after job
environment no Defines a name of environment, when deployment is done by this job
coverage no Define code coverage settings for a given job
retry no Define how many times a job can be auto-retried in case of failure

stages

stages is used to define stages used by jobs. The ordering of elements in stages defines the ordering of job's execution:

  1. Jobs of the same stage are run in parallel.
  2. Jobs of the next stage are run after the previous jobs complete successfully.

The following example defines 3 stages:

stages:
  - build
  - test
  - deploy
  1. First, all jobs of build stage are executed in parallel.
  2. If all jobs of build stage succeed, the test stage jobs are executed in parallel.
  3. If all jobs of test stage succeed, the deploy stage jobs are executed in parallel.
  4. If all jobs of deploy stage succeed, the commit is marked as passed .
  5. If any of the previous jobs fails, the commit is marked as failed and no jobs of further stage are executed.

There are also two edge cases worth mentioning:

  1. If no stages are defined in .gitlab-ci.yml, then the build, test, and deploy are allowed to be used as job's stage by default.
  2. If a job doesn't specify a stage, the job is assigned the test stage.

script

script is a shell script which is executed by the Runner. For example:

job:
  script: "bundle exec rspec"

This parameter can also contain several commands using an array:

job:
  script:
    - uname -a
    - bundle exec rspec

Sometimes, script commands will need to be wrapped in single (' ') or double (" ") quotes. For example, commands that contain a colon (:) need to be wrapped in quotes so the YAML parse knows to interpret the whole thing as a string, not a "key:value" pair. Be careful when using special characters: :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `` ```.

variables

Use variables keyword on a job level can define job variables. It works the same as its global-level equivalent, but allows us to define job-specific variables.

When the variables keyword is used on a job level, it overrides the global YAML job variables and predefined ones. To turn off global defined variables in the job, define an empty hash:

job_name:
  variables: {}

Job variables priority is defined in the variables documentation.

only and except

only and except are two parameters that set a job policy to limit when jobs are created:

  1. only defines the names of branches and tags for which the job will run.
  2. except defines the names of branches and tags for which the job will not run.

There are a few rules that apply to the job policy:

  • only and except are inclusive. if both only and except are defined in a job specification, the ref is filtered by only and except.
  • only and except allow the use of regular expressions.
  • only and except allow to specify a repository path to filter jobs for forks.

In addition, only and except allow the special keywords:

Value Description
branches When a branch is pushed.
tags When a tag is pushed.
api When pipeline has been triggered by a second pipelines API (not triggers API).
external When using CI services other than GitLab.
pipelines For multi-project triggers, created using the API with "CI_JOB_TOKEN".
pushes Pipeline is triggered by a "git push" by the user.
schedules For scheduled pipelines.
triggers For pipelines created using a trigger token.
web For pipelines created using "Run pipeline" button in GitLab UI (under the project's Pipelines).

In the example below, job will run only for refs that start with issue-, whereas all branches will be skipped:

job:
  # use regexp
  only:
    - /^issue-.*$/
  # use special keyword
  except:
    - branches

In the example below, job will run only for refs that are tagged, or if a build is explicitly requested via an API trigger or a Pipeline Schedule:

job:
  # use special keywords
  only:
    - tags
    - triggers
    - schedules

In the example below, the repository path can be used to have jobs executed only for the parent repository and not forks:

job:
  only:
    - branches@gitlab-org/gitlab-ce
  except:
    - master@gitlab-org/gitlab-ce

The above example will run job for all branches on gitlab-org/gitlab-ce, except master.

results matching ""

    No results matching ""